table of contents
GIT-MERGETOOL(1) | Git Manual | GIT-MERGETOOL(1) |
NAME¶
git-mergetool - Run merge conflict resolution tools to resolve merge conflicts
SYNOPSIS¶
git mergetool [--tool=<tool>] [-y | --[no-]prompt] [<file>...]
DESCRIPTION¶
Use git mergetool to run one of several merge utilities to resolve merge conflicts. It is typically run after git merge.
If one or more <file> parameters are given, the merge tool program will be run to resolve differences in each file (skipping those without conflicts). Specifying a directory will include all unresolved files in that path. If no <file> names are specified, git mergetool will run the merge tool program on every file with merge conflicts.
OPTIONS¶
-t <tool>, --tool=<tool>
If a merge resolution program is not specified, git mergetool will use the configuration variable merge.tool. If the configuration variable merge.tool is not set, git mergetool will pick a suitable default.
You can explicitly provide a full path to the tool by setting the configuration variable mergetool.<tool>.path. For example, you can configure the absolute path to kdiff3 by setting mergetool.kdiff3.path. Otherwise, git mergetool assumes the tool is available in PATH.
Instead of running one of the known merge tool programs, git mergetool can be customized to run an alternative program by specifying the command line to invoke in a configuration variable mergetool.<tool>.cmd.
When git mergetool is invoked with this tool (either through the -t or --tool option or the merge.tool configuration variable), the configured command line will be invoked with $BASE set to the name of a temporary file containing the common base for the merge, if available; $LOCAL set to the name of a temporary file containing the contents of the file on the current branch; $REMOTE set to the name of a temporary file containing the contents of the file to be merged, and $MERGED set to the name of the file to which the merge tool should write the result of the merge resolution.
If the custom merge tool correctly indicates the success of a merge resolution with its exit code, then the configuration variable mergetool.<tool>.trustExitCode can be set to true. Otherwise, git mergetool will prompt the user to indicate the success of the resolution after the custom tool has exited.
--tool-help
-y, --no-prompt
--prompt
-g, --gui
--no-gui
-O<orderfile>
CONFIGURATION¶
Everything below this line in this section is selectively included from the git-config(1) documentation. The content is the same as what’s found there:
mergetool.<tool>.path
mergetool.<tool>.cmd
mergetool.<tool>.hideResolved
mergetool.<tool>.trustExitCode
mergetool.meld.hasOutput
mergetool.meld.useAutoMerge
mergetool.vimdiff.layout
mergetool.hideResolved
mergetool.keepBackup
mergetool.keepTemporaries
mergetool.writeToTemp
mergetool.prompt
mergetool.guiDefault
TEMPORARY FILES¶
git mergetool creates *.orig backup files while resolving merges. These are safe to remove once a file has been merged and its git mergetool session has completed.
Setting the mergetool.keepBackup configuration variable to false causes git mergetool to automatically remove the backup files as files are successfully merged.
BACKEND SPECIFIC HINTS¶
vimdiff¶
Description
When specifying --tool=vimdiff in git mergetool Git will open Vim with a 4 windows layout distributed in the following way:
------------------------------------------ | | | | | LOCAL | BASE | REMOTE | | | | | ------------------------------------------ | | | MERGED | | | ------------------------------------------
LOCAL, BASE and REMOTE are read-only buffers showing the contents of the conflicting file in specific commits ("commit you are merging into", "common ancestor commit" and "commit you are merging from" respectively)
MERGED is a writable buffer where you have to resolve the conflicts (using the other read-only buffers as a reference). Once you are done, save and exit Vim as usual (:wq) or, if you want to abort, exit using :cq.
Layout configuration
You can change the windows layout used by Vim by setting configuration variable mergetool.vimdiff.layout which accepts a string where the following separators have special meaning:
The precedence of the operators is as follows (you can use parentheses to change it):
`@` > `+` > `/` > `,`
Let’s see some examples to understand how it works:
This is exactly the same as the default layout we have already seen.
Note that / has precedence over , and thus the parenthesis are not needed in this case. The next layout definition is equivalent:
layout = "LOCAL,BASE,REMOTE / MERGED"
If, for some reason, we are not interested in the BASE buffer.
------------------------------------------ | | | | | | | | | LOCAL | MERGED | REMOTE | | | | | | | | | ------------------------------------------
Only the MERGED buffer will be shown. Note, however, that all the other ones are still loaded in vim, and you can access them with the "buffers" command.
------------------------------------------ | | | | | MERGED | | | | | ------------------------------------------
When MERGED is not present in the layout, you must "mark" one of the buffers with an asterisk. That will become the buffer you need to edit and save after resolving the conflicts.
------------------------------------------ | | | | | | | | | | LOCAL | REMOTE | | | | | | | | | | ------------------------------------------
Three tabs will open: the first one is a copy of the default layout, while the other two only show the differences between (BASE and LOCAL) and (BASE and REMOTE) respectively.
------------------------------------------ | <TAB #1> | TAB #2 | TAB #3 | | ------------------------------------------ | | | | | LOCAL | BASE | REMOTE | | | | | ------------------------------------------ | | | MERGED | | | ------------------------------------------
------------------------------------------ | TAB #1 | <TAB #2> | TAB #3 | | ------------------------------------------ | | | | | | | | | | BASE | LOCAL | | | | | | | | | | ------------------------------------------
------------------------------------------ | TAB #1 | TAB #2 | <TAB #3> | | ------------------------------------------ | | | | | | | | | | BASE | REMOTE | | | | | | | | | | ------------------------------------------
Same as the previous example, but adds a fourth tab with the same information as the first tab, with a different layout.
--------------------------------------------- | TAB #1 | TAB #2 | TAB #3 | <TAB #4> | --------------------------------------------- | LOCAL | | |---------------------| | | BASE | MERGED | |---------------------| | | REMOTE | | ---------------------------------------------
Note how in the third tab definition we need to use parentheses to make , have precedence over /.
Variants
Instead of --tool=vimdiff, you can also use one of these other variants:
When using these variants, in order to specify a custom layout you will have to set configuration variables mergetool.gvimdiff.layout and mergetool.nvimdiff.layout instead of mergetool.vimdiff.layout
In addition, for backwards compatibility with previous Git versions, you can also append 1, 2 or 3 to either vimdiff or any of the variants (ex: vimdiff3, nvimdiff1, etc...) to use a predefined layout. In other words, using --tool=[g,n,]vimdiffx is the same as using --tool=[g,n,]vimdiff and setting configuration variable mergetool.[g,n,]vimdiff.layout to...
Example: using --tool=gvimdiff2 will open gvim with three columns (LOCAL, MERGED and REMOTE).
GIT¶
Part of the git(1) suite
11/20/2023 | Git 2.43.0 |